home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / LinkVar.3 < prev    next >
Encoding:
Text File  |  1995-03-08  |  3.6 KB  |  105 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) LinkVar.3 1.7 95/03/08 09:15:47
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_LinkVar tclc 7.0
  12. .BS
  13. .SH NAME
  14. .na
  15. Tcl_LinkVar, Tcl_UnlinkVar \- link Tcl variable to C variable
  16. .ad
  17. .SH SYNOPSIS
  18. .nf
  19. \fB#include <tcl.h>\fR
  20. .sp
  21. int
  22. \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
  23. .sp
  24. \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
  25. .SH ARGUMENTS
  26. .AS Tcl_Interp writable
  27. .AP Tcl_Interp *interp in
  28. Interpreter that contains \fIvarName\fR.
  29. Also used by \fBTcl_LinkVar\fR to return error messages.
  30. .AP char *varName in
  31. Name of global variable.
  32. .AP char *addr in
  33. Address of C variable that is to be linked to \fIvarName\fR.
  34. .AP int type in
  35. .na
  36. Type of C variable.  Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
  37. TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
  38. TCL_LINK_READ_ONLY to make Tcl variable read-only.
  39. .ad
  40. .BE
  41.  
  42. .SH DESCRIPTION
  43. .PP
  44. \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
  45. named by \fIvarName\fR in sync with the C variable at the address
  46. given by \fIaddr\fR.
  47. Whenever the Tcl variable is read the value of the C variable will
  48. be returned, and whenever the Tcl variable is written the C
  49. variable will be updated to have the same value.
  50. \fBTcl_LinkVar\fR normally returns TCL_OK;  if an error occurs
  51. while setting up the link (e.g. because \fIvarName\fR is the
  52. name of array) then TCL_ERROR is returned and \fIinterp->result\fR
  53. contains an error message.
  54. .PP
  55. The \fItype\fR argument specifies the type of the C variable,
  56. and must have one of the following values, optionally OR'ed with
  57. TCL_LINK_READ_ONLY:
  58. .TP
  59. \fBTCL_LINK_INT\fR
  60. The C variable is of type \fBint\fR.
  61. Any value written into the Tcl variable must have a proper integer
  62. form acceptable to \fBTcl_GetInt\fR;  attempts to write
  63. non-integer values into \fIvarName\fR will be rejected with
  64. Tcl errors.
  65. .TP
  66. \fBTCL_LINK_DOUBLE\fR
  67. The C variable is of type \fBdouble\fR.
  68. Any value written into the Tcl variable must have a proper real
  69. form acceptable to \fBTcl_GetDouble\fR;  attempts to write
  70. non-real values into \fIvarName\fR will be rejected with
  71. Tcl errors.
  72. .TP
  73. \fBTCL_LINK_BOOLEAN\fR
  74. The C variable is of type \fBint\fR.
  75. If its value is zero then it will read from Tcl as ``0'';
  76. otherwise it will read from Tcl as ``1''.
  77. Whenever \fIvarName\fR is
  78. modified, the C variable will be set to a 0 or 1 value.
  79. Any value written into the Tcl variable must have a proper boolean
  80. form acceptable to \fBTcl_GetBoolean\fR;  attempts to write
  81. non-boolean values into \fIvarName\fR will be rejected with
  82. Tcl errors.
  83. .TP
  84. \fBTCL_LINK_STRING\fR
  85. The C variable is of type \fBchar *\fR.
  86. If its value is not null then it must be a pointer to a string
  87. allocated with \fBmalloc\fR.
  88. Whenever the Tcl variable is modified the current C string will be
  89. freed and new memory will be allocated to hold a copy of the variable's
  90. new value.
  91. If the C variable contains a null pointer then the Tcl variable
  92. will read as ``NULL''.
  93. .PP
  94. If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
  95. variable will be read-only from Tcl, so that its value can only be
  96. changed by modifying the C variable.
  97. Attempts to write the variable from Tcl will be rejected with errors.
  98. .PP
  99. \fBTcl_UnlinkVar\fR removes the link previously set up for the
  100. variable given by \fIvarName\fR.  If there does not exist a link
  101. for \fIvarName\fR then the procedure has no effect.
  102.  
  103. .SH KEYWORDS
  104. boolean, integer, link, read-only, real, string, variable
  105.